Content
# Tool List
Starting from a public Douyin homepage, `sec_uid`, Douyin ID, or nickname, generate an auditable creator content insight report. Outputs include HTML, Markdown, and JSON.
[](https://github.com/tars1230/douyin-creator-insight/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
## Capabilities
- Parse homepage URL, `sec_uid`, Douyin ID, and nickname; fuzzy results require manual confirmation.
- Standardize video fields from different data sources.
- Select candidate highlight videos based on interaction signals and obtain available speech-to-text transcriptions.
- Perform blocking quality gates for parsing, video quantity, and transcription quality.
- Generate HTML, Markdown, and JSON reports.
This project only processes public data and does not bypass login, privacy, or platform access controls.
## Two Modes of Operation
### 1. As an Agent Skill
This is the primary usage. Install the repository in an agent environment that supports `SKILL.md` and configure Apify MCP. The agent calls the MCP tool according to [SKILL.md](SKILL.md) and then uses this repository's scripts to complete parsing, filtering, and report generation.
```bash
git clone https://github.com/tars1230/douyin-creator-insight.git
cp -R douyin-creator-insight ~/.workbuddy/skills/
```
`mcp.json.example` shows the MCP structure. Real tokens must be provided by environment variables or the host's secret store; do not submit them to the repository.
### 2. As a CLI
The CLI does not guess credentials or pretend "not captured" is successful. You must explicitly choose one of the following modes:
```bash
# Offline check: only parse input, do not generate a real report
python3 scripts/run_pipeline.py \
--creator https://www.douyin.com/user/<sec_uid> \
--dry-run
# Real execution: provide a module:function adapter
PYTHONPATH=/path/to/adapters:$PYTHONPATH \
python3 scripts/run_pipeline.py \
--creator https://www.douyin.com/user/<sec_uid> \
--adapter my_adapter:call_actor \
--max-videos 50 \
--transcript-count 3 \
--output-dir ./output
```
The adapter must implement the following call contract:
```python
def call_actor(*, actor: str, input: dict, wait_secs: int):
"""Return a list of dataset items or {'datasetItems': [...]} for profile calls."""
```
Nicknames or Douyin IDs also require a search adapter:
```bash
python3 scripts/run_pipeline.py \
--creator <nickname> \
--adapter my_adapter:call_actor \
--browser-adapter my_adapter:search_creator
```
`search_creator(*, query: str, max_results: int)` should return text, a list, or a dictionary containing public homepage URLs.
## Parameters
| Parameter | Description | Default |
|---|---|---|
| `--creator` | Homepage URL, `sec_uid`, Douyin ID, or nickname | Required |
| `--dry-run` | Offline parsing check | Choose one with `--adapter` |
| `--adapter` | Real actor adapter, `module:function` | Choose one with `--dry-run` |
| `--browser-adapter` | Nickname/Douyin ID search adapter | Optional |
| `--max-videos` | Maximum requested videos | 200 |
| `--transcript-count` | Requested transcription candidates | 5 |
| `--max-duration` | Maximum duration in the selection phase, minutes | 5 |
| `--output-dir` | Report directory | `./output` |
| `--format` | Any combination of `html json md` | All |
## Local Verification
Tests use fixtures only, do not call Douyin or Apify, and do not require tokens.
```bash
python3 -m compileall -q scripts tests
python3 -m unittest discover -s tests -v
```
CI runs the same set of tests on Python 3.10 and 3.12. Test coverage includes:
- CLI explicit mode contracts and exit codes;
- dry-run does not write output;
- End-to-end pipeline for 10 fixture videos to three-format reports;
- Skill metadata, private absolute paths, and common secret pattern scans.
## Data Sources and Costs
Default actors and fallbacks are listed in [references/apify-douyin-actors.md](references/apify-douyin-actors.md). Actor availability, input schema, pricing, and account quotas may change; verify on the corresponding Apify Actor page before running and test with a small sample first. The repository does not guarantee fixed time consumption, costs, or free quotas.
## Output and Examples
| File | Purpose |
|---|---|
| [docs/sample-report.html](docs/sample-report.html) | HTML report example |
| [docs/sample-report.md](docs/sample-report.md) | Markdown summary example |
| [docs/sample-report.json](docs/sample-report.json) | Structured data example |
Interaction sorting in reports is research-inspired and does not represent recommendation system weights or constitute business, investment, or platform growth guarantees.
## Known Limitations
- Upstream field or Actor behavior changes may cause quality gate blocking.
- Nickname searches may produce same-name candidates; low-confidence results require manual confirmation.
- Videos without narration, pure music, or upstream transcription failures may not have transcripts.
- CLI adapters are explicit extension points; this repository does not build-in token reading or browser login state reuse.
- Private accounts, bypassing access control, and unauthorized batch collection are not supported.
## Security and Contributions
Report security issues privately according to [SECURITY.md](SECURITY.md). Development and PR conventions are in [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[MIT](LICENSE)
