shuadouyin 0.3.5 → 0.4.1

package/.dy-build-commit

@@ -1 +1 @@
-74b35764d458acaeeff44eaef3fe9e9a99941ac8
+d9528376f4f68e7e7414bc7968f619267fd656b4

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.4.1 — 2026-10-31
+
+### 文档
+
+- README 加了两张图：一张能力总览，一张六格流程示意。两种语言共用同一组。
+- 图片不随 npm 包发布。它们是给 GitHub 页面看的，装包的人用不到，带上会把包从 343 kB 撑到 4.5 MB。
+
+## 0.4.0 — 2026-10-31
+
+### 新增
+
+- `chat recall` — 撤回自己发的一条私信。平台窗口是 3 分钟；超时后菜单里还有「撤回」但服务端会拒，所以它读响应而不是猜时间。没有二次确认，因此要 `--request-id`。
+- `chat inbox` — 谁在等我回。未读徽标不可靠（打开会话就清），所以按「最后一句是不是对方说的」判断，并把对方分享的作品 id 放进 `shared_works`。
+- `browse checkpoint` — 每批一条：走了哪条路、看到什么、每个交付条件是什么状态、下一步去哪里。进度从这些记录推导，不采信调用方的自述。
+- `browse start --text-file` — 一轮要交付什么、按什么标准判、什么时候停。写一次不能改，改条件就是换一轮。
+- `browse end --outcome` — `completed` 要求 checkpoint 真的达标，否则拒绝；`partial` 是诚实的交付。
+- `persona show` — 按段读取人格，每段带 `complete`。`context show` 从头截断，人格的「身份与声音」在后面，预算不够时会静静切掉。
+- `auth grant` / `auth revoke` / `auth grants` — 记住某个人可以做什么，带期限、每日上限和撤销记录。不是开关。
+
+### 改进
+
+- `page facts --selector` 只返回问到的标记：4440 → 618 字节。
+- `chat read` 不再复述上一条读到的消息内容：8832 → 4215 字节。
+- `comment list` 去掉每行重复的作品 id 和恒为 false 的布尔：2689 → 1849 字节。
+- `video digest` 不传 `--frames` 时按时长采样。之前两个默认值叠起来，让它从来没生效过。
+- 每个页面命令的返回会带 `persona` 字段，提醒这一轮还没读人格、读的是旧版本、或从没读过。
+- 三个预设各带一组同一事实的对照示例，说明这个声音在四种场景下怎么说话。
+
+### 修复
+
+- `chat read` 只读视口内的消息。真实群 13 条只返回 7 条，**漏掉的全是别人说的**。
+- `chat inbox` 把「新到旧」的数组当成「旧到新」，`awaiting_reply` 一直是反的。
+- 分享卡的作品 id 读不出来：`parsedContent` 是 getter，而 `own()` 故意拒绝 accessor。
+- `comment list` 和 `comment replies` 的关联信息移到结果顶层，不再每行重复。
+
+### 移除
+
+- `src/operations/actions.ts` — 提案/批准模型，从未被任何命令或模块引用。它的每日额度已由 `social goal` 和 `auth grant` 覆盖。
+
+## 0.3.5 及更早
+
+版本号在这一版之前没有随功能推进，所以更早的提交没有对应的版本记录。用 `dy update --check` 的 `commit` 字段判断新旧。

package/README.en.md

@@ -5,196 +5,185 @@
 
 <div align="center">
 
-# ShuaDouyin
+# ShuaDouyin · 刷抖音
 
-**An agent that browses Douyin with a persona and a memory. Open source.**
+<img src="docs/assets/shuadouyin-hero.png" alt="ShuaDouyin: browsing and search, comments and reactions, chat and sharing, live rooms, relationships, persona and memory" width="100%" />
 
-Browsing, comments, direct messages, live rooms, memory — one local CLI that
-leaves the judgement to whatever agent is driving it.
+**Let your AI Agent use Douyin with a persona and a memory.**
 
-<img src="https://img.shields.io/badge/node-%E2%89%A522.19-339933?logo=node.js&logoColor=white" alt="Node" />
-<img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
-<img src="https://img.shields.io/github/stars/9Ashwin/ShuaDouyin?style=social" alt="Stars" />
+A local command-line tool connecting your Agent, the Douyin page, and context that lasts.
+
+<img src="https://img.shields.io/badge/node-%E2%89%A522.19-339933?logo=node.js&logoColor=white" alt="Node.js 22.19+" />
+<img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+<img src="https://img.shields.io/github/stars/9Ashwin/ShuaDouyin?style=social" alt="GitHub Stars" />
+
+[Quick start](#quick-start) · [Capabilities](#capabilities) · [Agent integration](#agent-integration) · [Development](#development-and-contributing)
 
 </div>
 
----
+## What is this?
+
+ShuaDouyin's executable is `dy`. Give it to an AI Agent that can run shell commands to search content, inspect works and comments, interact with your authorization, handle messages and shares, visit live rooms, and keep sourced memories and relationship records.
 
-## What is this
+**You define the name, voice and boundaries. The Agent interprets and decides; `dy` supplies operations and evidence.** It bundles no model and schedules no tasks. It uses your existing Agent and local Chrome, with persona and memory stored locally across sessions.
 
-`dy` is a local command-line tool. It bundles no model, schedules nothing, and
-decides nothing about content — it provides the state, context and primitives
-one browsing round needs, and leaves the judgement to the agent calling it.
+## Quick start
 
-What it remembers for you: what this account likes, who it has talked to, which
-lines got an answer. What it will not decide for you: whether to send, what to
-say, or whether a person is worth knowing.
+You need **Node.js 22.19+, Chrome, and an Agent that can execute shell commands**.
 
-## Install
+### 1. Install the CLI and skill
 
 ```bash
 npm install -g shuadouyin
+dy --version
+dy skill install
 ```
 
-`dy` is then on your PATH. The package is `shuadouyin` and the command is `dy`;
-the published tarball ships a built `dist/`, so nothing compiles on install. The
-only requirement is a local Chrome — **no browser is downloaded**.
+The npm package is `shuadouyin`; the command is `dy`. The published package includes the build output and uses your local Chrome, without downloading another browser. The skill installer detects supported Agent directories and preserves existing copies it does not manage.
 
-Installing from source also works, and builds once:
+### 2. Create the workspace and log in
 
 ```bash
-npm install -g github:9Ashwin/ShuaDouyin
+dy init
+dy auth login
 ```
 
-This package is distributed from GitHub, not the npm registry.
+Scan the login QR code in the dedicated Chrome window. The default workspace is `~/.dy`; the browser login persists in `~/.dy/chrome`.
 
-<details>
-<summary><strong>Other options</strong></summary>
+### 3. Start a conversation with your Agent
 
-Into a private directory, without a global npm:
+> Use dy to help me set up a name, voice and boundaries. Then browse five works, pick one to inspect its frames and comments, and tell me what you observed. Only read this round; do not interact.
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/9Ashwin/ShuaDouyin/main/scripts/install.sh | sh
-```
+You can also start with a specific task:
 
-Uninstall:
+- **Research content:** “Search for AI coding, inspect two works, and separate what their titles, frames and comments tell us.”
+- **Continue a conversation:** “Check new messages in the conversation I specify and draft a reply using the earlier context.”
+- **Follow up:** “Review the people I have recorded and list follow-ups due today.”
+- **Review the day:** “Summarize today's local activity and receipts, clearly separating uncertain outcomes.”
 
-```bash
-npm uninstall -g shuadouyin
-```
+For manual terminal use, run `dy tui`. It needs an interactive terminal and shares the CLI's operations and state.
 
-Uninstalling keeps the bot, memories and account login in `~/.dy`.
+## Capabilities
 
-</details>
+![Six-panel comic: define a persona, search and browse, inspect works and comments, interact and share, visit live rooms, keep memory and relationships](docs/assets/shuadouyin-workflow.png)
+
+The artwork uses Chinese labels. The character represents a configurable Agent, not a fixed persona. Four sample positions and five comments came from an actual browsing run; the scenes are redrawn illustrations. The other panels show capabilities, not messages or gifts sent during that run.
+
+| Capability | Common entry points |
+| --- | --- |
+| Search works and people; browse a batch of feed items | `dy search` · `dy user search` · `dy feed sweep` |
+| Read works, sample frames, inspect comments and replies | `dy video digest` · `dy comment list` · `dy comment replies` |
+| Like, favorite, follow, post text or image comments | `dy video like` · `dy video favorite` · `dy user follow` · `dy comment post` · `dy comment image` |
+| Read messages, send text and images, quote a reply | `dy chat read` · `dy chat send` · `dy chat image` · `dy chat reply` |
+| Share a work as a link or native card | `dy chat share` · `dy chat forward` |
+| Read live-room info and chat, speak, send a named and priced gift | `dy live info` · `dy live chat` · `dy live say` · `dy live gift` |
+| Read persona, recall context, save sourced facts | `dy persona show` · `dy context show` · `dy memory add` |
+| Derive voice from actual writing, retain lessons, check wording | `dy persona evolve` · `dy learn keep` · `dy voice check` |
+| Track browsing rounds, goals, relationships and follow-ups | `dy browse start` · `dy social goal` · `dy social due` |
+| Inspect write receipts; prepare and save daily reports | `dy receipt get` · `dy report prepare` · `dy report save` |
+
+These are command entry points. Use `dy <command> --help` for required arguments, or `dy schema` for the complete command and field catalog.
+
+## Persona and memory across sessions
 
-Install the skill for an agent (optional):
+The default `~/.dy` workspace separates persona, people records, memory and the browser login:
+
+- **`AGENTS.md`** defines the Agent's identity, voice and boundaries. You can revise the settings.
+- **`PROFILES.md` and `memory/`** hold people records and sourced memories. Owner statements, page observations and inferences stay distinct. Markdown is the source of truth for memory bodies.
+- **`growth review`, `learn keep` and `persona evolve`** support reviewing activity, retaining lessons and deriving changes in voice. The caller decides what is worth keeping; a viewed work does not automatically become a lasting preference.
+
+Updating or reinstalling the CLI continues to use the existing workspace. Use the reset commands below when you want to start over.
+
+## Agent integration
+
+The [dy skill](skills/dy/SKILL.md) teaches Agents to use the tool, with topic-specific workflows in [references](skills/dy/references/). As an alternative to `dy skill install`, use the skills installer:
 
 ```bash
-dy skill install
+npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
 ```
 
-## Getting started
+Start each task by reading persona and relevant context:
 
 ```bash
-dy init                      # create the workspace, start onboarding
-dy onboarding show           # four questions: name, voice, facts about you, limits
-dy auth login                # open Chrome and scan the QR code
-dy feed next                 # next work in the recommended feed
-dy video info                # read the current work
+dy persona show
+dy context show --query "The question for this task"
+dy feed sweep --count 5
 ```
 
-The first login opens a dedicated Chrome window whose profile lives in
-`~/.dy/chrome`. That login is kept across restarts.
+Choose a work ID from the results, open its detail page, then sample it:
 
-Run `dy tui` when you want to browse and like by hand — a terminal interface
-over the same operations. It shares the CLI's implementation, so both see the
-same state. It needs a real terminal and refuses `--dry-run`.
+```bash
+dy video open <video-id>
+dy video digest --video-id <video-id> --limit 5
+```
 
-## What it does
+`dy guide` returns instructions matching the installed version; `dy schema` describes commands, arguments and effects. Run one workspace operation at a time to avoid account-lock conflicts.
 
-| Task | Commands |
-| --- | --- |
-| Browse the feed | `dy feed open` / `dy feed next` / `dy video info` |
-| Read works and comments | `dy video info` / `dy comment list` / `dy comment replies` |
-| Interact | `dy video like` / `dy video favorite` / `dy comment post` / `dy comment reply` |
-| Direct messages | `dy chat list` / `dy chat read` / `dy chat send` / `dy chat image` |
-| People | `dy user get` / `dy user search` / `dy user followers` / `dy user follow` |
-| Live rooms | `dy live info` / `dy live chat` / `dy live say` / `dy live gift` |
-| Search | `dy search` / `dy user search` |
-| Memory and persona | `dy memory add` / `dy memory search` / `dy context show` |
-| Browsing rounds | `dy browse start` / `dy browse watch` / `dy browse end` |
-| Relationships | `dy social goal` / `dy social list` / `dy social due` / `dy social log` |
-| Teach an agent to use it | `dy guide` |
+Success emits `{ok:true,data}` to stdout. Failure emits `{ok:false,error}` to stderr and exits nonzero. Writes use a unique `--request-id`. The `--dry-run` option validates input and the plan without connecting to Chrome, filling inputs or sending. See [docs/contracts.md](docs/contracts.md) for the full contract.
 
-See `dy schema` for every command, or `dy <command> --help`.
+## Actions and evidence
 
-## For agents
+- **A receipt before dispatch.** Replaying a confirmed request ID returns the saved receipt. Inspect `delivery_uncertain` outcomes instead of automatically resending. Native-card sharing currently cannot verify delivery and keeps dispatched shares uncertain.
+- **Stable identities.** Use the work, user and conversation IDs returned by the CLI. Display names are only labels.
+- **Samples are not full viewing.** Lists contain loaded content and generally report `complete: false`. The live picture is not returned as readable content. The Agent draws conclusions from the evidence it actually has.
+- **External actions need authorization.** Comments, messages, follows and live chat affect a real account. Gifts cost money and require explicit agreement plus a name-and-price check. Deletion and recall depend on platform conditions and cannot guarantee that content was unseen.
+- **Local login and data.** Automation may trigger verification, rate limits or account penalties. A person must complete verification; the project offers no bypass. `~/.dy` contains login state, messages and memories and should not be committed or shared. See [SECURITY.md](SECURITY.md).
+
+## Installation options and workspace management
+
+<details>
+<summary><strong>Other installation methods, uninstall and reset</strong></summary>
 
-`dy` is built for an agent to drive. Hand it to anything that can run a shell:
+Install from GitHub source, which runs a build:
 
 ```bash
-dy guide      # the full usage guide (~9000 characters); this is what the agent reads
+npm install -g github:9Ashwin/ShuaDouyin
 ```
 
-Or install `skills/dy` into your agent's skill directory. It carries five
-references: browsing and growth, memory and persona, reports, what to do when
-something fails, and **platform facts** — the last one is the record of what
-this project got wrong on the real page, and reading it saves repeating that.
-
-## Principles
-
-- **No judgement.** The CLI returns facts and candidates; the caller decides.
-  It acts on a real account, so the code's job is to make every action auditable
-  and reversible — not to decide whether the action is appropriate.
-- **A receipt before anything leaves.** Every write lands on disk before it can
-  dispatch, and replaying a request ID returns the original receipt. A
-  `delivery_uncertain` write is never retried automatically: it may already be
-  out, and sending again makes two.
-- **Identity is a stable id.** Display names collide and change; `sec_uid` does
-  not.
-- **Report what is readable.** The live picture is a canvas with no text layer,
-  so nothing is claimed about it. Comment lists are sampled and say so.
-- **Memory belongs to the account.** A new install is a new bot; it does not
-  inherit anyone else's conclusions.
-
-## Reset
+On macOS / Linux, an installer can use a private installation directory:
 
 ```bash
-dy bot reset           # show what would be cleared
-dy bot reset --write   # back up to ~/.dy-backup-<time>, then clear
-dy init                # create a fresh bot
+curl -fsSL https://raw.githubusercontent.com/9Ashwin/ShuaDouyin/main/scripts/install.sh | sh
 ```
 
-The Chrome login is kept, so no new scan is needed.
+Check installed skill copies against the current version:
 
-## Development
+```bash
+dy skill status
+```
 
-Requires Node.js 22.19+, pnpm, and a local Chrome.
+Remove an npm global installation while retaining `~/.dy`:
 
 ```bash
-pnpm install --frozen-lockfile --ignore-scripts
-pnpm build
-pnpm test            # unit tests
-pnpm test:browser    # isolated Chrome tests
-pnpm check           # Biome + tsc
+npm uninstall -g shuadouyin
 ```
 
-Output contracts, receipt states and storage semantics are in
-[docs/contracts.md](docs/contracts.md). Source layout, module ownership and the
-check sequence are in [AGENTS.md](AGENTS.md).
+Reset persona, memories and activity after a backup; keep the Chrome login:
 
-## Risks and limits
+```bash
+dy bot reset           # preview the scope
+dy bot reset --write   # back up and reset; use the returned backup path
+dy init                # create the workspace again
+```
 
-This tool drives a real Douyin account. Using it means accepting the following:
+</details>
 
-- **The account risk is yours.** Automated use of Douyin may trigger human
-  verification, rate limits or penalties. The project offers no bypass and will
-  not help you evade them. When a challenge appears, a person has to solve it in
-  the headed Chrome window.
-- **What is sent cannot be taken back.** Comments, direct messages, danmaku and
-  gifts are public and irreversible, and gifts cost real money. Check the target
-  and the text first; `--dry-run` shows the plan without acting.
-- **Local state is sensitive.** `~/.dy` holds the login, everything that was read
-  and the long-term memory. Do not commit it, screenshot it or put it somewhere
-  shared. See [SECURITY.md](SECURITY.md).
-- **What you read is not everything.** Lists are sampled and say
-  `complete: false`; the live picture is a canvas with no text. Concluding from a
-  sample is your judgement, not the tool's finding.
-- **It does not decide.** Whether to send, to whom, or whether a person is worth
-  knowing is not a decision the commands make, and being driven by an agent does
-  not lower that bar.
+## Development and contributing
 
-## Status
+Requires Node.js 22.19+, pnpm, and local Chrome.
 
-Early. Commands, error codes and response fields are public contracts and are
-kept stable; the database schema migrates with each release. CI runs the unit
-and isolated-Chrome tests on Ubuntu, macOS and Windows.
+```bash
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm build
+pnpm check           # Biome + TypeScript
+pnpm test            # unit tests
+pnpm test:browser    # temporary Chrome profile and fixture pages
+```
 
-## Contributing
+Browser tests use no account credentials. Passing them does not prove behavior on the real Douyin page. The project is early, and page changes can affect operations; error codes, arguments and response fields are maintained as public contracts.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Report security problems privately per
-[SECURITY.md](SECURITY.md).
+See [AGENTS.md](AGENTS.md) for development rules, [docs/architecture.md](docs/architecture.md) for the architecture, [CONTRIBUTING.md](CONTRIBUTING.md) to contribute, and [CHANGELOG.md](CHANGELOG.md) for release changes.
 
 ## License
 
-MIT
+[MIT](LICENSE)