shuadouyin 0.4.0 → 0.5.0

package/.dy-build-commit

@@ -1 +1 @@
-7251333bbc6e84fd193536885101c3b6ebf46c86
+e648c8d2d2d011a9aec54030287f9a8cf4947bf1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.0 — 2026-10-31
+
+### 新增
+
+- `video ai` — 读平台自己的 AI 对这条作品的描述。它能覆盖截图覆盖不到的：整条视频发生了什么、歌词唱什么、评论区在聊什么。**它是抖音在描述自己的内容，不是这个工具观察到的画面**，每条返回都带着这句话。
+- `video digest --ai` — 一次调用同时拿到采样画面和平台描述。两者放在不同字段里，不混在一起。
+- `video favorites` — 读自己收藏的作品，`--tab` 可换 喜欢 / 观看历史 / 稍后再看 / 我的预约。之前只能写收藏，看不到收藏了什么。
+
+### 改进
+
+- `context show` 对人格文件改用按段投影，和 `persona show` 一致。低预算时身份与声音不会被静静切掉。自由格式（没有 `##` 段）回退到原文而不是返回空。
+- 成功事件也记录耗时。之前只有失败记，所以「哪个命令慢」只能回答坏掉的那些。
+- 轮次摘要分开报 `browser_ms`（页面调用时间）和 `elapsed_ms`（轮次开了多久），并单独报 `duplicate_observations`——一个作品读两次，预算算一次，成本付两次。
+
+### 修复
+
+- `context show` 遇到只有标题没有小节的人格文件会返回空内容，等于说人格是空的。现在回退到原文。
+
+## 0.4.1 — 2026-10-31
+
+### 文档
+
+- README 加了两张图：一张能力总览，一张六格流程示意。两种语言共用同一组。
+- 图片不随 npm 包发布。它们是给 GitHub 页面看的，装包的人用不到，带上会把包从 343 kB 撑到 4.5 MB。
+
 ## 0.4.0 — 2026-10-31
 
 ### 新增

package/README.en.md

@@ -5,196 +5,202 @@
 
 <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.
+
+**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.
 
-## What is this
+## Quick start
 
-`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.
+### Copy an installation prompt (recommended)
 
-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.
+Copy the entire block to an Agent that can run shell commands. Install the skill first, then let its instructions guide CLI installation and setup:
+
+```text
+Please install the dy skill:
+npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
+
+Read the installed dy skill and follow it to check and install the CLI,
+guide me through persona setup and Douyin login, and verify that it works.
+Preserve existing settings and memories. Only install, configure, and run read-only checks.
+```
 
-## Install
+The skill includes CLI installation instructions. The Agent checks `dy --version` first and follows `references/setup.md` if the CLI is missing. The skill installer fetches its content from GitHub, so you do not need to open the repository and read the docs yourself. `dy` uses your existing Agent and needs no separate model API key. You log into Douyin yourself in local Chrome.
+
+### Manual installation
+
+You need **Node.js 22.19+, Chrome, and an Agent that can execute shell commands**.
+
+#### 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>
+### Start using it
 
-Into a private directory, without a global npm:
+After setup, send this to your Agent:
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/9Ashwin/ShuaDouyin/main/scripts/install.sh | sh
-```
+> Use dy to browse five works, pick one to inspect its frames and comments, and tell me what you observed. Only read this round; do not interact. If no persona has been configured yet, guide me through setup first.
 
-Uninstall:
+You can also start with a specific task:
 
-```bash
-npm uninstall -g shuadouyin
-```
+- **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.”
 
-Uninstalling keeps the bot, memories and account login in `~/.dy`.
+For manual terminal use, run `dy tui`. It needs an interactive terminal and shares the CLI's operations and state.
 
-</details>
+## Capabilities
+
+![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
+
+For a first installation, use the [installation prompt above](#copy-an-installation-prompt-recommended). The following covers skill entry points and the usual calling sequence.
+
+The [dy skill](skills/dy/SKILL.md) teaches Agents to install and use the tool, with topic-specific workflows in [references](skills/dy/references/). If the CLI is already installed, you can also run `dy skill install` to connect the skill.
+
+Start each task by reading persona and relevant context:
 
 ```bash
-dy skill install
+dy persona show
+dy context show --query "The question for this task"
+dy feed sweep --count 5
 ```
 
-## Getting started
+Choose a work ID from the results, open its detail page, then sample it:
 
 ```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 video open <video-id>
+dy video digest --video-id <video-id> --limit 5
 ```
 
-The first login opens a dedicated Chrome window whose profile lives in
-`~/.dy/chrome`. That login is kept across restarts.
+`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.
 
-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`.
+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.
 
-## What it does
+## Actions and evidence
 
-| 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` |
+- **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).
 
-See `dy schema` for every command, or `dy <command> --help`.
+## Installation options and workspace management
 
-## For agents
+<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)

package/README.md

@@ -5,177 +5,202 @@
 
 <div align="center">
 
-# 刷抖音 · ShuaDouyin
+# ShuaDouyin · 刷抖音
 
-**让 agent 带着人格和记忆使用抖音。开源。**
+<img src="docs/assets/shuadouyin-hero.png" alt="ShuaDouyin 刷抖音：浏览与搜索、评论与互动、私信与分享、直播与弹幕、关系与跟进、人格与记忆" width="100%" />
 
-浏览、评论、私信、直播、记忆——一个本地 CLI，判断权留给调用它的 agent。
+**让你的 AI Agent，带着人格和记忆使用抖音。**
 
-<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" />
+一个本地命令行工具，连接 Agent、抖音页面和持续积累的上下文。
 
-</div>
+<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" />
+
+[快速开始](#快速开始) · [功能一览](#功能一览) · [Agent 接入](#给-agent-接入) · [开发与参与](#开发与参与)
 
----
+</div>
 
 ## 这是什么
 
-`dy` 是一个本地命令行工具。它不内建模型、不调度、不做内容判断——它提供**一轮浏览所需的状态、上下文和操作原语**，判断由调用它的 agent 做。
+ShuaDouyin 的命令叫 `dy`。把它交给能执行 shell 的 AI Agent，就能搜索内容、浏览作品与评论、按授权互动、处理私信与分享、进入直播间，并保存有来源的记忆和关系记录。
 
-它替你记住的：这个账号喜欢什么、跟谁聊过、哪句话有回应。它不替你决定的：该不该发、发什么、这个人值不值得认识。
+**你定义名字、语气和边界，Agent 负责理解与判断，`dy` 提供操作和证据。** 项目不内建模型，也不运行定时任务；使用你已有的 Agent 和本机 Chrome。人设与记忆保存在本地，可以跨会话继续使用。
 
-## 安装
+## 快速开始
 
-```bash
-npm install -g shuadouyin
+### 复制给 Agent 安装（推荐）
+
+把下面整段复制给能执行 shell 的 Agent，先装 skill，再由技能引导完成 CLI 安装与设置：
+
+```text
+请帮我安装 dy 技能：
+npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
+
+安装后读取 dy skill，按技能指引检查并安装 CLI，
+带我完成人格设置和抖音登录，并验证是否可用。
+已有配置和记忆请保留，这次只做安装、配置和只读验证。
 ```
 
-`dy` 随即可用。**不下载浏览器**——用你本机已有的 Chrome。
+skill 已包含 CLI 的安装指引，Agent 会先检查 `dy --version`，缺少 CLI 时按 `references/setup.md` 继续安装。技能安装器会从 GitHub 获取内容，你无需手动打开仓库查文档。`dy` 使用你现有的 Agent，不需要单独配置模型 API Key；抖音登录由你在本机 Chrome 中完成。
 
-包叫 `shuadouyin`，命令叫 `dy`。发布包里带的是构建好的 `dist/`，装上就能跑，不需要本地再编译一次。
+### 自己安装
 
-<details>
-<summary><strong>其他</strong></summary>
+准备好 **Node.js 22.19+、Chrome，以及一个能执行 shell 的 Agent**。
 
-从源码装（会构建一次，几秒）：
+#### 1. 安装工具与 skill
 
 ```bash
-npm install -g github:9Ashwin/ShuaDouyin
+npm install -g shuadouyin
+dy --version
+dy skill install
 ```
 
-装到独立目录，不需要全局 npm：
+npm 包叫 `shuadouyin`，可执行命令叫 `dy`。发布包已包含构建产物；使用本机 Chrome，不额外下载浏览器。`dy skill install` 会为已检测到的 Agent 安装技能，已有的非托管副本会保留。
+
+#### 2. 建立工作区并登录
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/9Ashwin/ShuaDouyin/main/scripts/install.sh | sh
+dy init
+dy auth login
 ```
 
-卸载：
+在打开的专用 Chrome 窗口里扫码登录。工作区默认位于 `~/.dy`，浏览器登录保存在 `~/.dy/chrome`，后续继续使用。
 
-```bash
-npm uninstall -g shuadouyin
-```
+### 开始使用
 
-卸载保留 `~/.dy` 里的 bot、记忆和账号登录状态。
+设置好后，把这句话发给你的 Agent：
 
-</details>
+> 用 dy 刷 5 条，挑 1 条读画面和评论，告诉我看到了什么。这轮只看，不互动。如果还没设置人格，先带我完成设置。
 
-装 skill 给 agent 用（可选）：
+也可以从具体任务开始：
 
-```bash
-npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
-```
+- **带着问题找内容：**“搜一下 AI 编程，挑两条展开读，区分标题、画面和评论提供的信息。”
+- **继续已有对话：**“看看我指定会话的新消息，结合之前的上下文拟一条回复。”
+- **跟进关系：**“整理我已记录的人，看看今天有哪些到期的跟进事项。”
+- **回顾一天：**“根据今天的本地记录和收据写个摘要，结果不明的操作单独说明。”
+
+想自己操作终端界面，可以运行 `dy tui`；它需要真实终端，和 CLI 共用同一套操作与状态。
+
+## 功能一览
+
+![ShuaDouyin 六格漫画：设定人格、搜索与浏览、读作品与评论、互动与分享、直播与弹幕、记忆与关系](docs/assets/shuadouyin-workflow.png)
+
+图中角色代表可配置的 Agent，名字、语气和边界由你定义。四个采样点和五条评论来自一次实际浏览，画面为重绘；其他场景是功能示意，不代表本次执行了发送或送礼。
+
+| 能力 | 常用入口 |
+| --- | --- |
+| 搜索作品、找人、批量浏览推荐流 | `dy search` · `dy user search` · `dy feed sweep` |
+| 读取作品、采样画面、查看评论与回复 | `dy video digest` · `dy comment list` · `dy comment replies` |
+| 点赞、收藏、关注、发布文字或图片评论 | `dy video like` · `dy video favorite` · `dy user follow` · `dy comment post` · `dy comment image` |
+| 读取私信、发送文字和图片、引用回复 | `dy chat read` · `dy chat send` · `dy chat image` · `dy chat reply` |
+| 分享作品链接或原生卡片 | `dy chat share` · `dy chat forward` |
+| 读取直播信息与弹幕、发言、按名称和价格送礼 | `dy live info` · `dy live chat` · `dy live say` · `dy live gift` |
+| 读取人格、召回记忆、保存带来源的事实 | `dy persona show` · `dy context show` · `dy memory add` |
+| 从实际表达中更新声音、积累经验、自查文风 | `dy persona evolve` · `dy learn keep` · `dy voice check` |
+| 管理浏览轮次、目标、关系与跟进事项 | `dy browse start` · `dy social goal` · `dy social due` |
+| 查询操作收据、准备和保存日报 | `dy receipt get` · `dy report prepare` · `dy report save` |
+
+表中是命令入口，必填参数见 `dy <命令> --help`；完整命令与字段见 `dy schema`。
 
-或者用 CLI 自己装到 agent 目录：
+## 人格和记忆如何延续
+
+默认工作区 `~/.dy` 将人格、人物资料、记忆和账号登录分开保存：
+
+- **`AGENTS.md`** 定义这个 Agent 的身份、语气和边界，设定可以修改。
+- **`PROFILES.md` 与 `memory/`** 保存人物资料和带来源的记忆。用户明确表达的事实、页面观察和推测分开记录；Markdown 是记忆正文的来源。
+- **`growth review`、`learn keep` 与 `persona evolve`** 为回顾、经验和表达变化提供依据。是否值得保存由调用方判断，浏览不等于自动形成长期偏好。
+
+更新或重新安装 CLI 会继续使用原工作区。需要重新开始时，使用下方的重置命令。
+
+## 给 Agent 接入
+
+首次安装可以直接使用上面的[安装提示词](#复制给-agent-安装推荐)。下面是技能入口和日常调用顺序。
+
+[dy skill](skills/dy/SKILL.md) 负责教 Agent 安装和使用工具，主题流程放在 [references](skills/dy/references/) 中。如果已经安装 CLI，也可以运行 `dy skill install` 接入技能。
+
+每次任务先读人格和相关上下文，再读页面：
 
 ```bash
-dy skill install
-dy skill status   # 已装的副本和仓库是否一致
+dy persona show
+dy context show --query "这次要解决的问题"
+dy feed sweep --count 5
 ```
 
-## 开始使用
+从结果中选出作品 ID 后，先打开对应详情页，再采样：
 
 ```bash
-dy init                      # 建工作区，开始引导
-dy onboarding show           # 回答四个问题：名字、性格、关于你的事实、界限
-dy auth login                # 打开 Chrome 扫码登录抖音
-dy feed next                 # 刷下一条
-dy video info                # 读当前作品
+dy video open <video-id>
+dy video digest --video-id <video-id> --limit 5
 ```
 
-第一次登录会打开一个专用的 Chrome 窗口（profile 在 `~/.dy/chrome`），扫码后这个登录会一直保留。
+`dy guide` 提供与当前安装版本一致的使用说明；`dy schema` 提供命令、参数和副作用类型。一次只运行一个工作区操作，避免账号锁冲突。
 
-想手动刷、手动点赞时用 `dy tui`——一个覆盖同样操作的终端界面。它和 CLI 走同一套实现，所以两边看到的状态一致。需要在真实终端里运行（不接受管道输入），也不能和 `--dry-run` 一起用。
+成功输出 `{ok:true,data}` 到 stdout；失败输出 `{ok:false,error}` 到 stderr，并返回非零退出码。写入使用唯一的 `--request-id`；`--dry-run` 只验证参数和计划，不连接 Chrome、不填表、不发送。完整契约见 [docs/contracts.md](docs/contracts.md)。
 
-## 它能做什么
+## 操作与证据边界
 
-| 做什么 | 命令 |
-| --- | --- |
-| 刷推荐流 | `dy feed open` / `dy feed next` / `dy video info` |
-| 读作品与评论 | `dy video info` / `dy comment list` / `dy comment replies` |
-| 互动 | `dy video like` / `dy video favorite` / `dy comment post` / `dy comment reply` |
-| 私信 | `dy chat list` / `dy chat read` / `dy chat send` / `dy chat image` |
-| 人 | `dy user get` / `dy user search` / `dy user followers` / `dy user follow` |
-| 直播 | `dy live info` / `dy live chat` / `dy live say` / `dy live gift` |
-| 搜索 | `dy search` / `dy user search` |
-| 记忆与人格 | `dy memory add` / `dy memory search` / `dy context show` |
-| 人格自己长 | `dy persona evolve` / `dy persona history` / `dy persona rollback` |
-| 沉淀经验 | `dy learn keep` / `dy learn findings` |
-| 文风自查 | `dy voice check --text "…"` |
-| 浏览轮次 | `dy browse start` / `dy browse watch` / `dy browse end` |
-| 社交关系 | `dy social goal` / `dy social list` / `dy social due` / `dy social log` |
-| 让 agent 会用 | `dy guide` |
-
-完整命令见 `dy schema`，或 `dy <命令> --help`。
-
-## 给 agent 用
-
-`dy` 是为 agent 设计的。把它交给任何能跑 shell 的 agent：
+- **写之前先留收据。** 已确认的 request ID 重放时返回原收据；遇到 `delivery_uncertain` 先核对，不自动重发。原生卡片分享目前无法验证送达，发出后会保留不确定状态。
+- **用稳定 ID 定位。** 作品、用户和会话以 CLI 返回的稳定 ID 为准；昵称只用于展示。
+- **采样不等于完整观看。** 列表只包含已加载内容，通常标记 `complete: false`；直播画面不作为可读内容返回。判断由 Agent 根据实际证据作出。
+- **对外动作需要授权。** 评论、私信、关注和直播发言作用于真实账号；礼物会花真钱，必须明确同意并核对名称和价格。删除或撤回受平台条件限制，不能保证收回已被看到的内容。
+- **登录和数据留在本机。** 自动化可能触发验证、限流或账号处罚；验证需要真人完成，项目不提供绕过手段。`~/.dy` 含登录态、消息和记忆，不应提交或共享。详见 [SECURITY.md](SECURITY.md)。
+
+## 安装方式与工作区管理
+
+<details>
+<summary><strong>其他安装方式、卸载与重置</strong></summary>
+
+从 GitHub 源码安装，会执行构建：
 
 ```bash
-dy guide      # 返回完整的使用说明（约 3 万字），agent 读这个
+npm install -g github:9Ashwin/ShuaDouyin
 ```
 
-或者把 skill 装进你的 agent 技能目录，这样它知道什么时候该用 `dy`、怎么用：
+macOS / Linux 也可以使用独立目录安装器：
 
 ```bash
-npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
+curl -fsSL https://raw.githubusercontent.com/9Ashwin/ShuaDouyin/main/scripts/install.sh | sh
 ```
 
-`skills/dy` 里按主题分成八个参考文件：浏览与成长、记忆与人格、社交、直播、日报、自我改进、命令全表，以及**平台事实**——最后一个是踩过的坑，读它能省掉一次重来。
+检查 skill 副本与当前版本是否一致：
 
-`SKILL.md` 本身只有两百来行，是每次对话都会加载的那部分；参考文件按需读。
+```bash
+dy skill status
+```
 
-## 设计原则
+卸载 npm 全局安装的命令，保留 `~/.dy`：
 
-- **不做判断。** `dy` 不内建模型。它返回事实和候选，判断留给调用方。它对着一个真实账号操作，所以代码的职责是让每个动作可审计、可回滚，而不是替你决定这个动作该不该做。
-- **写之前先落收据。** 每条写入在可能发出之前就已落盘，重放同一个 request ID 返回原收据。`delivery_uncertain` 永远不自动重试——那条可能已经发出去了，再发就是两条。
-- **身份用稳定 ID。** 昵称会重名会改，`sec_uid` 不会。
-- **读到什么说什么。** 直播画面是 canvas，读不到就不报内容；评论是抽样，标 `complete: false`。
-- **记忆跟账号走。** 换一个安装就是新的 bot，不继承别人的判断。
+```bash
+npm uninstall -g shuadouyin
+```
 
-## 重置
+重置人格、记忆及活动状态，会先备份；Chrome 登录保留：
 
 ```bash
-dy bot reset           # 看会清掉什么（不改动）
-dy bot reset --write   # 备份到 ~/.dy-backup-<时间> 后清空
-dy init                # 建新的 bot
+dy bot reset           # 只预览范围
+dy bot reset --write   # 备份后重置，以返回的备份路径为准
+dy init                # 重新建立工作区
 ```
 
-Chrome 登录会保留，不用重新扫码。
+</details>
 
-## 开发
+## 开发与参与
 
 需要 Node.js 22.19+、pnpm 和本机 Chrome。
 
 ```bash
 pnpm install --frozen-lockfile --ignore-scripts
 pnpm build
+pnpm check           # Biome + TypeScript
 pnpm test            # 单元测试
-pnpm test:browser    # 隔离 Chrome 的浏览器测试
-pnpm check           # Biome + tsc
+pnpm test:browser    # 临时 Chrome profile + fixture 页面
 ```
 
-输出契约、收据状态和存储语义见 [docs/contracts.md](docs/contracts.md)。源码结构、模块归属和检查流程见 [AGENTS.md](AGENTS.md)。
-
-## 风险与边界
-
-这是一个操作真实抖音账号的工具。用它意味着接受下面几件事：
-
-- **账号风险由你承担。** 自动化使用抖音可能触发平台的人机验证、限流或处罚。项目不提供任何绕过手段，也不会帮你规避风控。验证弹出来时，需要真人在有头的 Chrome 里完成。
-- **发出去的东西撤不回来。** 评论、私信、弹幕、礼物都是对外且不可逆的。送礼花的是真钱。发之前先确认对象和内容，`--dry-run` 可以先看计划。
-- **本地状态含敏感信息。** `~/.dy` 里有登录态、读过的消息和长期记忆。不要提交、不要截图、不要放进共享目录。详见 [SECURITY.md](SECURITY.md)。
-- **读到的不是全部。** 列表是抽样并标 `complete: false`，直播画面是 canvas 读不到字。基于抽样下结论是你自己的判断，不是工具的结论。
-- **它不做判断。** 该不该发、发给谁、这个人值不值得认识，命令不会替你决定，也不会因为调用方是 agent 就降低门槛。
-
-## 状态
-
-早期阶段。命令、错误码和返回字段是公开契约，会尽量保持稳定；数据库结构随版本迁移。CI 在 Ubuntu、macOS 和 Windows 上跑单元测试与隔离 Chrome 测试。
-
-## 参与
+浏览器测试不使用账号凭据，通过测试不等于通过真实抖音页面验证。项目仍处于早期阶段，页面变化可能影响操作；错误码、参数和返回字段按公开契约维护。
 
-见 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题走私密报告渠道，见 [SECURITY.md](SECURITY.md)。
+开发规则见 [AGENTS.md](AGENTS.md)，架构见 [docs/architecture.md](docs/architecture.md)，贡献方式见 [CONTRIBUTING.md](CONTRIBUTING.md)，版本变化见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 许可
 
-MIT
+[MIT](LICENSE)

package/dist/app.js

@@ -5,6 +5,7 @@ import { CliError, normalizeError } from "./errors.js";
 import { Knowledge, knowledgeOperation, validateKnowledge } from "./knowledge.js";
 import { migrateLegacyLayout } from "./migrate.js";
 import { askDouyin } from "./operations/ai-search.js";
+import { readAiSummary } from "./operations/ai-summary.js";
 import { rounds } from "./operations/browsing.js";
 import { audio, capture, noteImage, noteSlide, observe } from "./operations/capture.js";
 import { captureChatImage, listChats, readChat } from "./operations/chat.js";
@@ -18,6 +19,7 @@ import { closeComments, commentVoice, knownVoices, listComments, listReplies, ph
 import { inspectCreator } from "./operations/creator.js";
 import { digest } from "./operations/digest.js";
 import { pageFactsRead } from "./operations/facts.js";
+import { readFavorites } from "./operations/favorites.js";
 import { readImage } from "./operations/image-file.js";
 import { readInbox } from "./operations/inbox.js";
 import { resolveLink } from "./operations/links.js";
@@ -252,9 +254,16 @@ export class App {
                         // starting. Reading "the open round" after the fact would attach a
                         // long sweep to whichever round happened to be open when it ended.
                         const open = rounds(await this.store.events()).find((round) => round.status === "open");
-                        const data = open && result && typeof result === "object"
-                            ? { ...result, _browse: { round_id: open.id, started_at: open.started_at } }
-                            : result;
+                        // How long the page call took is measured here, where the clock is
+                        // already running. Only failures carried a duration before, so
+                        // "which command is slow" could be answered for the ones that broke
+                        // and never for the ones that worked — which is the question a
+                        // caller actually has.
+                        const elapsed = Math.max(0, Math.round(performance.now() - started));
+                        const browse = open ? { round_id: open.id, started_at: open.started_at, elapsed_ms: elapsed } : null;
+                        const data = !open && !(result && typeof result === "object")
+                            ? result
+                            : { ...result, _elapsed_ms: elapsed, ...(browse ? { _browse: browse } : {}) };
                         await this.store.append(operation, data);
                     }
                     const notices = {
@@ -656,6 +665,10 @@ export class App {
                 return userRelations(session, { ...input, relation: operation === "user.following" ? "following" : "followers" }, signal);
             case "ai.ask":
                 return askDouyin(session, input, signal);
+            case "video.ai":
+                return readAiSummary(session, input, signal);
+            case "video.favorites":
+                return readFavorites(session, input, signal);
             case "person.read":
                 input.user_id = resourceID(input.resource ?? "", "user");
                 return readPerson(session, input, signal);

package/dist/catalog.js

@@ -900,6 +900,20 @@ export const COMMANDS = [
         effect: "account_write",
         guidance: "Read video info first. --value false removes the like; an already matching state does not click the button. Image posts use their own controls and never fall back to the video button.",
     },
+    {
+        id: "video.favorites",
+        description: "List the works this account has saved, from its own profile tab",
+        flags: [
+            {
+                key: "target",
+                name: "--tab <name>",
+                description: "收藏 (default), 喜欢, 观看历史, 稍后再看, 我的预约",
+                type: "string",
+            },
+        ],
+        effect: "read",
+        guidance: "Opens this account's own profile and reads the work grid on the named tab. Writing a favorite already existed; this is the read side, without which a caller adds to a collection it cannot see. Only works loaded in the window are listed and the page states no total, so complete is always false. A tab that comes back empty is empty, not still loading: the reader waits for the grid to change and then reports what is there.",
+    },
     {
         id: "video.favorite",
         description: "Set the desired favorite state of the current video or image post",
@@ -912,6 +926,13 @@ export const COMMANDS = [
         flags: [{ key: "output", name: "--output <path>", description: "PNG output path", type: "string" }],
         effect: "local",
     },
+    {
+        id: "video.ai",
+        description: "Read the platform's own summary of the current work",
+        flags: [video],
+        effect: "read",
+        guidance: "Opens the work's AI panel and returns what Douyin's model wrote about it. This covers what frames cannot — the whole video, the lyrics, what the comments are about — and it is the platform describing its own content rather than an observation: an answer here can be wrong in ways a screenshot cannot. Every response carries that distinction in its limits, and complete:false means the panel had not finished writing, so the text is partial. Use video digest for what the page shows and this for what the platform says about it; a claim worth repeating should be checked against the work.",
+    },
     {
         id: "video.digest",
         description: "Gather what a work is about: identity, sampled positions and loaded comments",
@@ -929,6 +950,13 @@ export const COMMANDS = [
             },
             { key: "limit", name: "--limit <count>", description: "Comments to read (default 8)", type: "number" },
             { key: "output", name: "--output <directory>", description: "Frame output directory", type: "string" },
+            {
+                key: "ai",
+                name: "--ai",
+                description: "Also read the platform's own summary of the work",
+                type: "boolean",
+                default: false,
+            },
         ],
         effect: "local",
         guidance: "A title states the form, not the point. Three positions inside a work carry the argument, and the comment section says who is watching and what they took from it. Sampling avoids the opening and the end, which are the least informative parts. Frames are viewport screenshots and are labelled as samples, never as a claim about the whole work. A work under 15 seconds is not sampled: it is its own summary. Use --frames 0 to skip seeking entirely.",

package/dist/knowledge.js

@@ -481,7 +481,46 @@ export class Knowledge {
                         remaining -= kept.length;
                         return { content: kept.join(""), truncated: kept.length < chars.length };
                     };
-                    const documentViews = documents.map((document) => ({ ...document, ...excerpt(document.content, 8000) }));
+                    // The persona is projected by section, not sliced from the front.
+                    //
+                    // Slicing is right for memories and wrong for a persona: identity and
+                    // voice sit after the role introduction, so a budget that runs out
+                    // silently removes the part the agent is supposed to sound like, and
+                    // nothing in the output says it was cut. The projection returns whole
+                    // sections and marks each one, and persona show uses the same function
+                    // so two callers cannot disagree about what the persona is.
+                    const documentViews = documents.map((document) => {
+                        if (document.file !== "AGENTS.md")
+                            return { ...document, ...excerpt(document.content, 8000) };
+                        const sectionBudget = Math.min(4000, remaining);
+                        const surface = personaSurface(BOT_ID, document.file, document.revision, document.content, sectionBudget);
+                        // A file with no sections is not a persona with nothing in it. The
+                        // projection cannot read it, so the document is passed through as
+                        // written and the flags say the shape was not understood — an empty
+                        // content field would say the persona itself is empty.
+                        if (surface.needs_interpretation)
+                            return { ...document, ...excerpt(document.content, 8000) };
+                        const parts = surface.parts.filter((part) => part.complete);
+                        // The remaining sections are reported, not dropped: a caller that sees
+                        // complete:false knows to raise the budget or read the document.
+                        remaining -= surface.characters;
+                        return {
+                            ...document,
+                            content: parts
+                                .map((part) => `${part.name === "identity" ? "## 身份与声音" : part.name}\n\n${part.text}`)
+                                .join("\n\n"),
+                            truncated: !surface.complete,
+                            persona: {
+                                name: surface.name,
+                                sections: surface.parts.map((part) => ({
+                                    name: part.name,
+                                    complete: part.complete,
+                                })),
+                                missing: surface.missing,
+                                needs_interpretation: true,
+                            },
+                        };
+                    });
                     const memoryViews = packed.items.map(({ hit, body, truncated }) => {
                         const row = hit.entry.row;
                         const short = (value, max) => Array.from(value).slice(0, max).join("");

package/dist/operations/ai-summary.js

@@ -0,0 +1,52 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "../errors.js";
+import { control } from "./navigation.js";
+export const AI_SUMMARY_LIMITS = [
+    "Written by Douyin's model about its own content, not observed by this tool. Quote it as the platform's description, never as something seen here.",
+    "It can describe what the frames cannot: the whole video, lyrics, and what the comments are about.",
+    "Read the ending marker as the signal it finished. Without it the answer was still streaming, and this returns complete:false rather than the partial text.",
+];
+export async function readAiSummary(session, input, signal) {
+    const open = await session.call("video.info", input);
+    const workID = open.video?.id ?? null;
+    const point = await session.call("ai.entry.point", {});
+    await session.tab.mouse.click(point.x, point.y);
+    // The panel streams. Two reads in a row with the same text means it stopped;
+    // waiting for a non-empty read alone would return the first sentence of an
+    // answer that is still being written.
+    const deadline = Date.now() + 30_000;
+    let previous = "";
+    let stable = 0;
+    let last = { complete: false, summary: "", why: "" };
+    while (Date.now() < deadline) {
+        signal.throwIfAborted();
+        await delay(600, undefined, { signal });
+        last = await session.call("ai.summary", {});
+        // The disclaimer is the page stating the answer is done, which is stronger
+        // evidence than a stable read.
+        if (last.complete) {
+            if (last.summary && last.summary === previous)
+                stable++;
+            else
+                stable = 0;
+            previous = last.summary;
+            if (stable >= 1)
+                break;
+        }
+    }
+    if (!last.summary)
+        throw new CliError("timeout", "The AI panel did not produce a summary", {
+            hint: last.why || "The entry may have opened a different panel, or the page changed.",
+        });
+    // A panel stays open across feed moves and would be read as this work's
+    // summary. Closing is best-effort: a panel that is already gone has nothing
+    // to close, and failing here would throw away a summary already read.
+    await control(session, "chat.close").catch(() => undefined);
+    return {
+        work_id: workID,
+        summary: last.summary,
+        complete: last.complete && stable >= 1,
+        limits: AI_SUMMARY_LIMITS,
+    };
+}
+//# sourceMappingURL=ai-summary.js.map

package/dist/operations/browsing.js

@@ -203,6 +203,25 @@ export function roundSummary(events, id) {
         inspected,
         interacted: [...interacted].length,
         elapsed_ms: elapsed,
+        // Time spent inside page calls, apart from how long the round was open. A
+        // round can be open for an hour with four minutes of browser work in it,
+        // and the difference is the caller thinking, not the tool being slow.
+        browser_ms: (() => {
+            let total = 0;
+            for (const event of inside) {
+                const data = record(event);
+                if (typeof data._elapsed_ms === "number" && data._elapsed_ms >= 0)
+                    total += data._elapsed_ms;
+            }
+            return total;
+        })(),
+        // The same work returned by more than one command. Counting it once is
+        // right for the budget and misleading for cost: reading a work twice is
+        // paid for twice.
+        duplicate_observations: (() => {
+            const all = observations(inside);
+            return all.length - uniqueObservations(all).length;
+        })(),
         budget: round.budget,
         // What the round is delivering against, and how far along it is. The
         // qualified count comes from the checkpoints, so it says what the caller

package/dist/operations/digest.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { classifyComment } from "../comment-stance.js";
 import { CliError } from "../errors.js";
+import { AI_SUMMARY_LIMITS, readAiSummary } from "./ai-summary.js";
 import { captureSnapshot, noteImage, noteSlide } from "./capture.js";
 import { listComments } from "./comments.js";
 // Long works earn more samples; a nine-second clip is its own summary. The
@@ -53,6 +54,11 @@ export async function digest(session, store, input, signal) {
     const duration = initial.video?.duration ?? null;
     const frames = [];
     const limitations = [];
+    // Requested before the frames so a failure here is the caller's error rather
+    // than a digest that quietly comes back with pictures and no summary.
+    const ai = input.ai
+        ? await readAiSummary(session, { ...input, video_id: initial.video?.id ?? initial.note?.id ?? undefined }, signal)
+        : null;
     const directory = store.path(join("captures", `digest-${work.id}`));
     // An image post is a set of pictures, and the set is the work. Sampling a video
     // means picking moments inside one; sampling an image post means looking at every
@@ -164,9 +170,15 @@ export async function digest(session, store, input, signal) {
         },
         frames,
         comments,
+        // The platform's own description, when asked for. It goes in a field of its
+        // own and never into `frames`: one is what was seen, the other is what the
+        // platform says, and merging them would make the difference invisible at the
+        // point a caller reads it.
+        ...(ai ? { platform_summary: ai } : {}),
         scope: frames.length ? "sampled_positions_and_loaded_comments" : "loaded_comments",
         limitations: [
             "Frames are screenshots of the viewport: they show what was on screen, not a claim about the whole work.",
+            ...(ai ? [AI_SUMMARY_LIMITS[0]] : []),
             ...limitations,
         ],
     };

package/dist/operations/favorites.js

@@ -0,0 +1,67 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "../errors.js";
+import { navigate } from "./navigation.js";
+// The tab labels the profile offers. Reading a different tab is the same code
+// path with a different label, so this is not only about favorites.
+const TABS = ["收藏", "喜欢", "观看历史", "稍后再看", "我的预约"];
+export async function readFavorites(session, input, signal) {
+    const requested = (input.target ?? "收藏").trim();
+    if (!TABS.includes(requested))
+        throw new CliError("invalid_argument", `Unknown profile tab "${requested}"`, {
+            hint: `Accepted: ${TABS.join(", ")}`,
+        });
+    const limits = [
+        "Screenshots and the private area are not read; this is the work grid as the page renders it.",
+        "Only works loaded in the current window are listed. Scroll the page for more.",
+        "A work being listed here says it is on this tab, not why the account saved it.",
+    ];
+    await navigate(session, "https://www.douyin.com/user/self", "profile", signal);
+    // The tab strip renders with the header, a moment after the route settles. A
+    // read taken on the navigation's word found no tabs at all and reported the
+    // page as changed.
+    const tabDeadline = Date.now() + 6000;
+    while (Date.now() < tabDeadline) {
+        signal.throwIfAborted();
+        try {
+            await session.call("profile.tab.point", { target: requested });
+            break;
+        }
+        catch (error) {
+            if (error instanceof CliError && error.code === "selector_changed") {
+                await delay(300, undefined, { signal });
+                continue;
+            }
+            throw error;
+        }
+    }
+    const before = await session.call("profile.tab.works", {});
+    const point = await session.call("profile.tab.point", { target: requested });
+    await session.tab.mouse.click(point.x, point.y);
+    await delay(400, undefined, { signal });
+    // The grid replaces the previous tab's list rather than appending to it, so
+    // waiting for the first work to differ is what tells the two apart. Reading
+    // before that returns the previous tab and calls it this one.
+    const deadline = Date.now() + 6000;
+    let works = before.works;
+    while (Date.now() < deadline) {
+        signal.throwIfAborted();
+        await delay(300, undefined, { signal });
+        const read = await session.call("profile.tab.works", {});
+        if (read.works.length && JSON.stringify(read.works) !== JSON.stringify(before.works)) {
+            works = read.works;
+            break;
+        }
+        // An empty tab is a real answer: the list is empty rather than still
+        // loading. It is taken once the wait has run out, never on the first read.
+        works = read.works;
+    }
+    return {
+        tab: requested,
+        works,
+        // The page does not state a total, so "complete" would be a claim about a
+        // number nothing here knows.
+        complete: false,
+        limits,
+    };
+}
+//# sourceMappingURL=favorites.js.map

package/dist/operations/validate.js

@@ -90,6 +90,13 @@ export function validate(operation, raw) {
             throw new CliError("invalid_argument", `--${key} must be an integer from ${minimum} to ${maximum}`);
     }
     switch (operation) {
+        case "video.favorites":
+            // The tab name is checked before Chrome starts. A page command that
+            // validated after connecting reported browser_not_running to a caller
+            // whose actual mistake was a typo in the tab name.
+            if (input.target && !["收藏", "喜欢", "观看历史", "稍后再看", "我的预约"].includes(input.target))
+                throw new CliError("invalid_argument", "--tab must be 收藏, 喜欢, 观看历史, 稍后再看 or 我的预约");
+            break;
         case "search":
         case "user.search":
             if (!input.query?.trim() || input.query.length > 300)

package/dist/page-adapter.js

@@ -765,6 +765,29 @@ var DouyinPage = (() => {
     const label = clean(container.getAttribute("aria-label") || container.getAttribute("title")) || images.map((image) => image.label).filter(Boolean).join(" ");
     return { name: label || null, images, requires_visual: !label };
   }
+  function aiEntryPoint() {
+    const entries2 = findRendered(document, '[class*="ai-douyin-entry"]').filter((element) => {
+      const box2 = element.getBoundingClientRect();
+      return box2.width > 0 && box2.height > 0 && box2.bottom > 0 && box2.top < innerHeight;
+    });
+    const entry = one(entries2, "AI summary entry on screen");
+    const box = entry.getBoundingClientRect();
+    return { x: Math.round(box.left + box.width / 2), y: Math.round(box.top + box.height / 2) };
+  }
+  function aiSummary() {
+    const text = document.body.innerText;
+    const marker = "\u4EE5\u4E0A\u5185\u5BB9\u7531AI\u751F\u6210";
+    const end = text.indexOf(marker);
+    if (end < 0) return { complete: false, summary: "", why: "The AI panel is not showing a finished answer" };
+    const head = text.slice(0, end);
+    const tabs = /(?:TA的作品|相关推荐)\s*\n?\s*评论?\s*\n?\s*相关推荐\s*\n*/;
+    const after = tabs.test(head) ? head.slice(head.search(tabs) + (head.match(tabs)?.[0].length ?? 0)).trim() : head.trim();
+    return {
+      complete: true,
+      summary: clean(after),
+      why: ""
+    };
+  }
   function readShare(container) {
     let videoID2 = null;
     let kind = null;
@@ -2650,10 +2673,22 @@ var DouyinPage = (() => {
     for (const anchor of anchors) {
       const id = /\/video\/(\d+)/.exec(anchor.getAttribute("href") ?? "")?.[1];
       if (!id || works.has(id)) continue;
-      works.set(id, { url: anchor.href, title: clean(anchor.textContent) });
+      const text = clean(anchor.textContent);
+      const half = text.slice(0, Math.floor(text.length / 2));
+      works.set(id, { url: anchor.href, title: half && text === half + half ? half : text });
     }
     return [...works.values()];
   }
+  function profileTabPoint(label) {
+    const entries2 = [...document.querySelectorAll('[data-e2e="user-tab-icon"]')].map((icon) => ({ icon, label: clean(icon.parentElement?.textContent) })).filter((entry2) => entry2.label === label);
+    const entry = one(entries2, `profile tab "${label}"`);
+    const box = entry.icon.getBoundingClientRect();
+    if (box.width === 0 || box.height === 0) fail("selector_changed", `The "${label}" tab is not laid out`);
+    return { x: Math.round(box.left + box.width / 2), y: Math.round(box.top + box.height / 2) };
+  }
+  function tabWorks() {
+    return readProfileWorks();
+  }
   var hoverPoint = null;
   async function execute(operation, args) {
     switch (operation) {
@@ -2934,6 +2969,10 @@ var DouyinPage = (() => {
           index
         };
       }
+      case "ai.entry.point":
+        return aiEntryPoint();
+      case "ai.summary":
+        return aiSummary();
       case "chat.detail.open":
         return findRendered(document, '[class*="messageMessageListlist"],[data-e2e="message-list"]').length > 0;
       case "chat.recall.target":
@@ -3208,6 +3247,10 @@ var DouyinPage = (() => {
       }
       case "profile.works":
         return { works: readProfileWorks().length };
+      case "profile.tab.point":
+        return profileTabPoint(args.target ?? "\u6536\u85CF");
+      case "profile.tab.works":
+        return { works: tabWorks() };
       case "user.get": {
         const id = userIdentity(args.user_id);
         const matches = find(document, '[data-e2e="user-info"],[data-e2e="user-detail"]');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shuadouyin",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"packageManager": "pnpm@10.34.7",
 	"description": "Browse Douyin with a persistent bot persona and a memory of its own",
 	"type": "module",
@@ -21,6 +21,7 @@
 		"skills",
 		".dy-build-commit",
 		"!dist/**/*.map",
+		"!docs/assets",
 		"!dist/**/*.d.ts",
 		".dy-build-origin"
 	],

package/skills/dy/references/commands.md

@@ -104,6 +104,8 @@ dy note capture --index 0 --output x.png
 
 ```bash
 dy video digest [--frames N --limit 8]    # 标题 + 采样画面 + 评论；不写 --frames 就按时长自动选
+dy video ai                              # 平台自己的 AI 对这条作品的描述
+dy video digest --ai                     # 一次拿到截图和平台描述
 dy video seek --at 120                    # 跳到第 120 秒
 dy video observe --at 200 --seconds 4 --frames 2   # 在指定位置采样
 dy video play [--video-id <id>]           # 播放
@@ -116,6 +118,10 @@ dy video audio --seconds 10 --output a.webm
 
 `--frames 0` 只读身份和评论，不采样——筛候选时用这个，比每条都截图快得多。
 
+**`video ai` 看的是平台模型写的描述，不是画面。** 它能覆盖截图覆盖不到的：整条视频发生了什么、歌词唱什么、评论区在聊什么。但它是抖音在描述自己的内容，可能错、可能空泛、可能顺着你说——所以它返回的每条都带 `limits` 说明这一点。
+
+用截图能确认的事实用 `digest`；想知道「这条到底讲了什么」用 `ai`，但引述时要说「平台的说法」，不能说成「我看到的」。`complete: false` 表示它还没写完，不要把那半段当全文。
+
 `--frames 0` 跳过所有采样只读评论（最快）；短片自动不采样并说明原因。
 
 `video.seek` 越界会**拒绝**而不是截断——传了超出时长的位置说明你猜错了时长，需要知道。
@@ -126,7 +132,8 @@ dy video audio --seconds 10 --output a.webm
 
 ```bash
 dy video like --value true|false
-dy video favorite --value true|false
+dy video favorite --video-id <id> --value true|false   # 收藏/取消
+ dy video favorites                              # 读自己的收藏列表（--tab 可换 喜欢/观看历史/稍后再看）
 dy user follow --value true|false
 ```